Inside Macintosh: QuickDraw GX Objects /

Chapter 6 - Transform Objects / Transform Objects Reference

Functions / Getting and Setting the Mapping

GXSetShapeMapping

You can use the GXSetShapeMapping function to assign a new mapping to the transform object associated with a specified shape.

void GXSetShapeMapping(gxShape target, const gxMapping *map);

target

A reference to the shape whose transform you want to assign the mapping to.

map

A pointer to a mapping structure containing the matrix you want to assign as the mapping property of the target shape's transform.

DESCRIPTION

The GXSetShapeMapping function copies information from the mapping structure pointed to by the map parameter into the mapping property of the transform object associated with the shape referenced by the target parameter.

Calling this function is almost equivalent to

GXSetTransformMapping(GXGetShapeTransform(myShape),theMapping);

except that, if the source shape's transform object is shared with other shapes, GXSetShapeMapping creates a new copy of the transform object, attaches it to the source shape, and changes the mapping of the copy. That way, calling this function does not produce side effects on other shapes.

You can specify nil for the map parameter, in which case this function sets the mapping property of the target shape's transform to the identity matrix. (An identity mapping has no transforming effect on shape geometries that it is applied to.)

SPECIAL CONSIDERATIONS

You can provide any values for the elements of the mapping structure pointed to by the map parameter, with one exception: the lower-right element of this matrix (element [2][2]) may not be 0.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
Notices (debugging version)
mapping_unaffected

SEE ALSO

To assign a mapping directly to a transform object, use the GXSetTransformMapping function, described on page 6-55.

For information about the mapping property of the transform object, see the section "Mapping" beginning on page 6-10. For information about mapping matrices in general, see the mathematics chapter of Inside Macintosh: QuickDraw GX Environment and Utilities.